function openHelpService(varargin)
    % openHelpService - 打开帮助文档服务
    %
    % 语法:
    %   openHelpService()  % 使用配置文件中的默认文档
    %   openHelpService(helpFilePath)  % 指定文档路径
    %   openHelpService('ConfigKey', 'help_pdf_path')  % 使用配置键
    %
    % 输入参数:
    %   helpFilePath - 可选，帮助文档路径（相对或绝对路径）
    %   'ConfigKey'  - 可选，配置文件中的键名
    %
    % 说明:
    %   - 基于第4条规则（架构分离原则），将打开帮助文档功能独立封装
    %   - 自动读取 mbdWorkflowTool_config.yml 配置文件
    %   - 使用 ProjectPathManager 获取项目根目录
    %   - 使用 yamlread 读取配置
    %   - 支持相对路径和绝对路径
    %   - 使用系统默认应用程序打开文档（PDF、Word等）
    %   - 包含完整的错误处理和用户友好的错误提示
    %
    % 示例:
    %   % 使用配置文件默认设置
    %   openHelpService();
    %
    %   % 指定文档路径（相对于项目根目录）
    %   openHelpService('README.pdf');
    %
    %   % 使用绝对路径
    %   openHelpService('D:\workspace\zhefei\zhefei_mbd_platform\README.pdf');
    %
    % 作者: MBD Platform Team
    % 日期: 2025-10-19
    % 版本: 2.0
    
    % 解析输入参数
    p = inputParser;
    addOptional(p, 'helpFilePath', '', @ischar);
    addParameter(p, 'ConfigKey', 'pdf_path', @ischar);
    parse(p, varargin{:});
    
    helpFilePath = p.Results.helpFilePath;
    configKey = p.Results.ConfigKey;
    
    % 如果没有指定文档路径，从配置文件读取
    if isempty(helpFilePath)
        helpFilePath = readHelpPathFromConfig(configKey);
    end
    
    % 获取项目根目录（使用ProjectPathManager）
    try
        % 尝试通过ProjectPathManager获取项目根目录
        projectRoot = getProjectRoot();
    catch ME
        warning('openHelpService:ProjectRootNotFound', ...
            '无法获取项目根目录: %s\n将使用文件相对路径', ME.message);
        projectRoot = pwd;
    end
    
    % 构建完整路径
    if ~isAbsolutePath(helpFilePath)
        % 相对路径，使用项目根目录
        fullPath = fullfile(projectRoot, helpFilePath);
    else
        % 绝对路径
        fullPath = helpFilePath;
    end
    
    % 检查文件是否存在
    if ~exist(fullPath, 'file')
        % 基于第2条规则（错误处理原则）：明确报告错误，不使用fallback
        error('openHelpService:FileNotFound', ...
            ['帮助文档未找到: %s\n\n', ...
             '请检查以下路径:\n', ...
             '配置路径: %s\n', ...
             '完整路径: %s\n', ...
             '项目根目录: %s\n\n', ...
             '提示: 请检查配置文件 mbdWorkflowTool_config.yml 中的帮助文档路径设置。'], ...
            helpFilePath, helpFilePath, fullPath, projectRoot);
    end
    
    % 使用系统默认应用程序打开文件
    try
        if ispc
            % Windows系统使用winopen
            winopen(fullPath);
        elseif ismac
            % macOS系统使用open命令
            system(['open "' fullPath '"']);
        elseif isunix
            % Linux系统使用xdg-open命令
            system(['xdg-open "' fullPath '"']);
        else
            error('openHelpService:UnsupportedOS', ...
                '不支持的操作系统。请手动打开文档: %s', fullPath);
        end
        
        fprintf('已打开帮助文档: %s\n', fullPath);
        
    catch ME
        % 基于第2条规则：明确报告错误
        error('openHelpService:OpenFailed', ...
            ['无法打开帮助文档: %s\n\n', ...
             '错误信息: %s\n\n', ...
             '请尝试手动打开该文档。'], ...
            fullPath, ME.message);
    end
end

function helpPath = readHelpPathFromConfig(configKey)
    % 从配置文件读取帮助文档路径
    % 基于第4条规则（架构分离原则），在service内部处理配置读取
    
    try
        % 获取配置文件路径
        currentFile = mfilename('fullpath');
        utilsDir = fileparts(currentFile);
        appsDir = fileparts(utilsDir);
        configPath = fullfile(appsDir, 'mbdWorkflowTool_config.yml');
        
        if ~exist(configPath, 'file')
            % 配置文件不存在，使用默认值
            warning('openHelpService:ConfigNotFound', ...
                '配置文件未找到: %s\n使用默认路径', configPath);
            helpPath = 'README.pdf';
            return;
        end
               
        % 读取配置
        config = yamlread(configPath);
        
        % 获取帮助文档路径
        if isfield(config, 'help') && isfield(config.help, configKey)
            helpPath = config.help.(configKey);
        else
            % 配置项不存在，使用默认值
            warning('openHelpService:ConfigKeyNotFound', ...
                '配置键 "help.%s" 未找到，使用默认路径', configKey);
            helpPath = 'README.pdf';
        end
        
    catch ME
        % 读取配置失败，使用默认值
        warning('openHelpService:ConfigReadFailed', ...
            '读取配置文件失败: %s\n使用默认路径', ME.message);
        helpPath = 'README.pdf';
    end
end

function projectRoot = getProjectRoot()
    % 获取项目根目录
    % 使用ProjectPathManager（如果可用）
    % 否则使用文件路径推断
    
    try
        % 尝试使用ProjectPathManager
        % 先检查是否在路径中
        if exist('ProjectPathManager', 'class') ~= 8
            % 添加project_configuration到路径
            currentFile = mfilename('fullpath');
            utilsDir = fileparts(currentFile);
            appsDir = fileparts(utilsDir);
            toolsDir = fileparts(appsDir);
            projectRoot = fileparts(toolsDir);
            configDir = fullfile(projectRoot, 'project_configuration');
            addpath(configDir);
        end
        
        % 使用ProjectPathManager初始化（确保单例已创建）
        % 这样ProjectPathManager的rootDir会被正确设置
        ProjectPathManager.getInstance();
        
        % 更可靠的方法：通过当前文件路径推断
        currentFile = mfilename('fullpath');
        utilsDir = fileparts(currentFile);      % tools/apps/utils
        appsDir = fileparts(utilsDir);          % tools/apps
        toolsDir = fileparts(appsDir);          % tools
        projectRoot = fileparts(toolsDir);       % 项目根目录
        
    catch ME
        % 如果ProjectPathManager不可用，使用文件路径推断
        warning('openHelpService:ProjectPathManagerUnavailable', ...
            'ProjectPathManager不可用: %s\n使用文件路径推断', ME.message);
        
        currentFile = mfilename('fullpath');
        utilsDir = fileparts(currentFile);      % tools/apps/utils
        appsDir = fileparts(utilsDir);          % tools/apps
        toolsDir = fileparts(appsDir);          % tools
        projectRoot = fileparts(toolsDir);       % 项目根目录
    end
end

function tf = isAbsolutePath(path)
    % 检查是否为绝对路径
    % Windows: 以盘符开头 (如 C:\) 或 UNC路径 (\\server\)
    % Unix/Mac: 以 / 开头
    
    if ispc
        % Windows系统
        tf = ~isempty(regexp(path, '^[A-Za-z]:\\', 'once')) || ...
             ~isempty(regexp(path, '^\\\\', 'once'));
    else
        % Unix/Mac系统
        tf = ~isempty(regexp(path, '^/', 'once'));
    end
end

